home *** CD-ROM | disk | FTP | other *** search
/ Technotools / Technotools (Chestnut CD-ROM)(1993).ISO / lang_c / mscheap2 / heap.man < prev    next >
Text File  |  1990-03-13  |  59KB  |  1,707 lines

  1.  
  2.                Manual for Replacement Heap Manager for MSC
  3.                -------------------------------------------
  4.  
  5.         Copyright (c) 1990 by Optimal Software, All Rights Reserved
  6.  
  7.             Optimal Software, 4 Lacy Lane, Nashua, NH 03061-2151
  8.  
  9.                    603-880-9844              CIS [73710,406]
  10.  
  11.  
  12.  
  13.             This file contains manual pages for the replacement
  14.             heap manager library.
  15.  
  16.  
  17. I. Overview
  18.  
  19.    This section provides introductory information on the heap manager
  20.    library.  The function descriptions are in Part II.
  21.  
  22.    1. Organization
  23.  
  24.       Part I of the heap manager library manual is organized as follows
  25.  
  26.         - Section 2 provides general rules for using the replacement
  27.                     heap manager library.
  28.  
  29.         - Section 3 describes the variables and types that are
  30.                     declared by the heap manager and used by
  31.                     the library routines.
  32.  
  33.         - Section 4 summarizes the heap management functions and
  34.                     provides a brief description of each function.
  35.  
  36.         - Section 5 explains the contents of the heap manager include
  37.                     files heap.h and heap.i.
  38.  
  39.       Part II consists of detailed reference pages for the individual
  40.       heap access functions.
  41.  
  42.  
  43.    2. Using the heap management fuctions
  44.  
  45.       This section provides the background information and the general
  46.       rules that apply to programs using the replacement heap manager.
  47.  
  48.  
  49.       a. Function prototypes
  50.  
  51.          All of the heap management functions are declared as
  52.          prototypes with both a return type and a complete argument
  53.          list.  The functions that are unique to the replcement heap
  54.          manager are disabled by the STDMSC symbol to provide strict
  55.          compatibility with the original malloc.h.
  56.  
  57.  
  58.       b. Stack checking
  59.  
  60.          Stack checking is disabled for all heap management functions.
  61.  
  62.  
  63.       c. Type checking
  64.  
  65.          The heap management functions are declared with complete
  66.          argument lists.
  67.  
  68.  
  69.       d. Error handling
  70.  
  71.          The replacement heap manager handles errors the same way
  72.          the original MSC heap manager does.  Where possible, the
  73.          function detecting the error returns a result indicating
  74.          that a problem exists.  Invalid pointers passed to a heap
  75.          access function produce an error message on stderr.
  76.  
  77.  
  78.          i. _HEAPDEBUG -- debugging heap problems
  79.  
  80.             This symbol enables an alternate set of functions that
  81.             diagnose heap problems.  The functions that change the
  82.             heap are replace by equivalents that check the heap
  83.             consistency with _heapchk(), perform the standard heap
  84.             operation, and then record the transaction for diagnostic
  85.             reports triggered by errors.
  86.  
  87.             The defined value of the symbol is taken to be the stream
  88.             on which error reports should appear. For example,
  89.             -D_HEAPDEBUG=stdout sends error reports to the standard
  90.             output stream.
  91.  
  92.             Enabling _HEAPDEBUG also enables a stringent form of pointer
  93.             checking.  Instead of a test on the value of the pointer
  94.             offset, _HEAPDEBUG checks that a matching entry exists in
  95.             the heap (this is free as _HEAPDEBUG must traverse the heap
  96.             to check for errors anyway).  Thus _HEAPDEBUG guarantees that
  97.             no pointer that happens to have a zero offset can masquerade
  98.             as a heap pointer.
  99.  
  100.             STDMSC overrides _HEAPDEBUG.  If both are defined _HEAPDEBUG
  101.             is ignored.
  102.  
  103.             For further details see section IV.D. of the heapinfo.txt file.
  104.  
  105.  
  106.          ii. _HEAPTRACE -- tracing heap activity
  107.  
  108.             This symbol enables an alternate set of functions that
  109.             trace heap activity.  Functions that change the heap are
  110.             replaced by equivalents that write a transaction record
  111.             to the trace log file after every heap access.  The
  112.             transaction reports give the sequence number, the name
  113.             of the function, the value of the parameters, the source
  114.             file and line number and the returned result.
  115.  
  116.             The defined value of the symbol is taken to be the stream
  117.             on which transaction reports should appear.  For example,
  118.             -D_HEAPTRACE=stdout sends reports to the standard output file.
  119.  
  120.             Enabling _HEAPTRACE implies that _HEAPDEBUG is enabled as well.
  121.  
  122.             STDMSC overrides _HEAPTRACE.  If both are defined _HEAPTRACE
  123.             is ignored.
  124.  
  125.             For further details see section IV.E of the heapinfo.txt file.
  126.  
  127.  
  128.    3. Global variables and standard types
  129.  
  130.  
  131.       a. size_t _amblksiz;
  132.  
  133.          The _amblksize variable controls the size of allocation
  134.          requests made to the operating system.  It is identical
  135.          to the _amblksiz of the MSC heap manager, described on
  136.          page 33 of the MSC 5.1 Optimizing Compiler Run-Time Library
  137.          Reference, with one exception.  The replacement heap manager
  138.          does not impose a power-of-two requirement on the size of
  139.          allocated blocks.  This change gives application programs
  140.          precise control over the heap and limits heap fragmentation.
  141.  
  142.  
  143.       b. int _heapmode;
  144.  
  145.          In order to expedite allocation operations there is a global
  146.          list of free chunks.  The list is doubly linked, and ordered
  147.          as defined by _heapmode.  MSC does not appear to have a free
  148.          list.  It seems to rely on the hope that garbage collection is
  149.          infrequent to compensate for the fact than searching the entire
  150.          heap for free entries is extremely expensive.
  151.  
  152.          The replacement heap manager optimizes its operations based on
  153.          the value of the variable _heapmode.
  154.  
  155.  
  156.             i. _HEAPTIME
  157.  
  158.                The _HEAPTIME setting sacrifices space efficiency for
  159.                performance.  The free list is not maintained in order
  160.                and allocation takes the first entry that fits (LIFO).
  161.                This setting is useful for programs with small amounts
  162.                of volatile data.
  163.  
  164.                This setting also tries to meet allocation needs without
  165.                merging free blocks.  If the allocation fails the free
  166.                list is condensed and another attempt is made.  The MSC
  167.                heap manager operates in a similar manner, fragmenting
  168.                the heap and wasting space in an attempt to save time.
  169.  
  170.  
  171.             ii. _HEAPSIZE
  172.  
  173.                If _heapmode is _HEAPSIZE the heap manager minimizes
  174.                the space occupied by the heap by maintaining the free
  175.                list in address order (first fit).  This technique tends
  176.                to keep the in-use heap entries in low memory so that
  177.                _heappack() can release unused space back to DOS.  This
  178.                setting is useful for programs which spawn other programs,
  179.                or use large buffers, or are generally tight on memory.
  180.  
  181.  
  182.             iii. _HEAPSPACE
  183.  
  184.                If _heapmode is _HEAPSPACE the heap manager minimizes
  185.                the wasted heap space by maintaining the free list in
  186.                order of size (best fit).  This technique permits the
  187.                most effective use of the available heap space.  It is
  188.                useful for programs that must handle overflow via disk
  189.                files.  The efficient utilization of heap memory minimizes
  190.                the need for disk access.
  191.  
  192.  
  193.             iv. Other values
  194.  
  195.                Undefined values for _heapmode produce results identical
  196.                to _HEAPTIME.
  197.  
  198.  
  199.          Note that changing the _heapmode on the fly does not
  200.          automatically re-order the free list.  Neither does it cause
  201.          problems.  As the heap is used the free list will lose the
  202.          old ordering and conform to the new optimization.
  203.  
  204.          The default mode is described by _HEAPMODE and may be set
  205.          from the compiler command line when the library is built by
  206.          defining the symbol _HEAPMODE.  E.g., -D_HEAPMODE=_HEAPSIZE.
  207.          The factory setting is _HEAPTIME as this is the closest
  208.          approximation to the original MSC heap manager.
  209.  
  210.  
  211.       c. size_t _heappad
  212.  
  213.          A classic problem in heap management is writing past the end
  214.          of a buffer obtained from the heap.  This typically produces
  215.          extremely hostile effects.  As the routines that handle
  216.          heap-generated buffers are usually embedded in the lower layers
  217.          of software, checking them can be tedious.
  218.  
  219.          One method of testing this mode of failure is to add extra space
  220.          at the ends of the allocated areas.  If the failures stop, there
  221.          is evidence of a heap problem.  Of course, changing sizes moves
  222.          things around which can turn errors on and off randomly so the
  223.          evidence is flimsy.  The problem with this debugging technique
  224.          is that changing the buffer lengths manually is a time-consuming,
  225.          error-prone operation with marginal utility.
  226.  
  227.          The replacement heap manager provides a control for automatically
  228.          extending all heap allocation requests.  Thus an initialization
  229.          parameter is enough to provide evidence for or against heap
  230.          problems.  Typically the padding is set to one or two times the
  231.          size of the structures being manipulated.
  232.  
  233.          Because the padding affects the distance between the data area
  234.          and the heap control structures it cannot be changed after the
  235.          heap has been initialized.  The heap manager takes a copy of
  236.          _heappad when the heap is initialized and uses the copy thereafter.
  237.          Thus _heappad must be set as early as possible, typically in main().
  238.  
  239.          Note that command-line wild cards processed with setargv.obj use
  240.          the heap before main is started.  Normal programs without wild
  241.          card expansion can use:
  242.  
  243.                extern size_t _heappad;   /* declare the global variable */
  244.  
  245.                int main()
  246.                {
  247.                _heappad = 100;           /* set the value */
  248.                }
  249.  
  250.          But programs with wild card handling enabled (those linked with
  251.          the special version of setargv.obj) must use:
  252.  
  253.                size_t _heappad = 100;    /* define the global and its value */
  254.  
  255.                int main()
  256.                {
  257.                }
  258.  
  259.          This sets the value at compile/link time rather than at run time.
  260.  
  261.          The safety margins are automatically filled when a heap entry
  262.          is allocated.  The fill pattern is initially alternating bits,
  263.          0x55, but it is reset by every call to _heapset().  _Heapchk()
  264.          compares the two safety margins and reports _HEAPBADPTR if they
  265.          differ.
  266.  
  267.  
  268.       d. Heap data structures and types
  269.  
  270.          Heap.h defines several structures which represent heap
  271.          control blocks.  The _heapinfo structure and the size_t type
  272.          are identical to the MSC versions.  The other structures are
  273.          unique to the replacement heap manager.
  274.  
  275.  
  276.          i. _ARENA
  277.  
  278.             The _ARENA structure describes a block of memory obtained
  279.             from the operating system or other source of heap memory.
  280.             Arenas are linked together in a doubly-linked list.  Within
  281.             each arena the heap manager keeps track of the used and
  282.             free regions with _CHUNK control blocks.
  283.  
  284.  
  285.          ii. _CHUNK
  286.  
  287.             The _CHUNK structure describes a block of memory that is
  288.             either in use by an application program or free to be
  289.             allocated.  The chunks within an arena are linked together
  290.             in a doubly-linked list.  The free chunks are also linked
  291.             into the global free list.
  292.  
  293.  
  294.          iii. _LINK
  295.  
  296.             The _LINK structure describes a pair of pointers to
  297.             aligned structures.  It is the basis for the doubly-linked
  298.             lists on which the heap management algorithms are based.
  299.  
  300.  
  301.       e. The linker vs module-arity
  302.  
  303.          The replacement heap management functions are designed to
  304.          superceed the original functions contained in the standard
  305.          C run-time libraries.  Unfortunately, the standard linker is
  306.          not able to handle the replacement process reliably.  It
  307.          requires the /NOE switch to disable extended library searches
  308.          in order to avoid spurious messages of the form:
  309.  
  310.              "symbol multiply defined, use /NOE"
  311.  
  312.          With the /NOE switch, the linker is unable to resolve references
  313.          between libraries properly.  For example, your application
  314.          program might refer to _fmalloc() and printf().  The _fmalloc()
  315.          reference will be resolved when the replacement heap library
  316.          is processed.  The printf() reference will be resolved when
  317.          the default C run-time library is processed.  But printf() calls
  318.          _getbuf() which calls malloc() which is in a module with _fmalloc().
  319.          The linker ignores the malloc() in the replacement library and uses
  320.          the one in the default library pulling in a second definition of
  321.          _fmalloc().  So there are two definitions of _fmalloc(), one from
  322.          each library, and the linker complains:
  323.  
  324.             "symbol defined more than once"
  325.  
  326.          The simplest solution to this problem is to remove the MSC
  327.          heap management functions from the default C run-time library.
  328.          This solution requires absolute faith in the compatibility and
  329.          reliability of the replacement heap manager.  A less drastic
  330.          method is to arrange the functions in the replacement library
  331.          into modules that exactly match the modules in the original
  332.          library.  This insures that collisions of the form described
  333.          above are impossible.  It also allows easy integration of the
  334.          replacement library with the old library because the one-for-one
  335.          module matching is assured by use of the same module names.
  336.  
  337.          Thus the replacement library is not fully decomposed into
  338.          individual functions.  Multi-function modules in the original
  339.          library have been replicated in the replacement library.  The
  340.          non-singular modules are as follows:
  341.  
  342.  
  343.             Module name                 Functions included
  344.             ------------    --------------------------------------------
  345.             fheapchk        _fheapchk    _fheapset
  346.  
  347.             fmalloc         _ffree       _fmalloc     free(f)    malloc(f)
  348.  
  349.             fmsize          _fmsize      _msize(f)
  350.  
  351.             freect          _freect      _memavl      _memmax
  352.  
  353.             nheapchk        _nheapchk    _nheapset  
  354.  
  355.             nmalloc         _nfree       _nmalloc     free(n)    malloc(n)
  356.  
  357.             xheapchk        _heapchk     _heapset     _heapwalk
  358.  
  359.  
  360.             Functions with an (f) suffix exist in libraries built with
  361.             the "far" data address model ("compact", "large", and "huge"
  362.             models).  Functions with an (n) suffix exist in libraries
  363.             build with the "near" data address model ("small" and "medium").
  364.          
  365.  
  366.    4. Memory allocation summary
  367.  
  368.       There are three heaps involved in the run-time library.  The "near"
  369.       heap uses the default data segment.  The "far" heap uses memory
  370.       from the operating system.  The default heap is the same as one of
  371.       the first two heaps.  It always matches the size of the default
  372.       data addressing model.
  373.       
  374.  
  375.       a. This list covers all of the memory allocation functions.  Functions
  376.          unique to the replacement heap manager are mark with an '*'.
  377.  
  378.  
  379.          alloca       Allocates memory from the stack
  380.  
  381.          calloc       Allocates memory for an array from the default heap
  382.  
  383.                     * _ncalloc applies to the near heap
  384.                     * _fcalloc applies to the far heap (size <= SIZE_MAX)
  385.                     * _hcalloc applies to the far heap (any size)
  386.  
  387.          _expand      Adjusts the size of an entry in the default heap
  388.  
  389.                     * _nexpand applies to the near heap
  390.                     * _fexpand applies to the far heap (size <= SIZE_MAX)
  391.                     * _hexpand applies to the far heap (any size)
  392.  
  393.          free         Releases memory back to the default heap (reverse malloc)
  394.  
  395.                       _nfree applies to the near heap
  396.                       _ffree applies to the far heap
  397.                     * _hfree applies to the far heap
  398.  
  399.          _freect      Estimates number of items that could be allocated (near)
  400.  
  401.          halloc       Allocates storage for a huge array from the far heap
  402.  
  403.          _heapchk     Verifies the integrity of the default heap
  404.  
  405.                       _nheapchk applies to the near heap
  406.                       _fheapchk applies to the far heap
  407.                     * _hheapchk applies to the far heap
  408.  
  409.        * _heapdump    Creates a detailed report on the default heap
  410.  
  411.                     * _nheapdump applies to the near heap
  412.                     * _fheapdump applies to the far heap (includes debug info)
  413.                     * _hheapdump applies to the far heap (includes debug info)
  414.  
  415.        * _heappack    Returns heap memory to the operating system.
  416.  
  417.                     * _nheappack applies to the near heap (non-fuctional)
  418.                     * _fheappack applies to the far heap
  419.                     * _hheappack applies to the far heap
  420.  
  421.          _heapset     Fills unused default heap memory with a single value
  422.  
  423.                       _nheapset applies to the near heap
  424.                       _fheapset applies to the far heap
  425.                     * _hheapset applies to the far heap
  426.  
  427.        * _heapstat    Translates heap status codes to text strings
  428.  
  429.          _heapwalk    Traverses the default heap, reporting on each entry
  430.  
  431.                       _nheapset applies to the near heap
  432.                       _fheapset applies to the far heap
  433.                     * _hheapset applies to the far heap
  434.  
  435.        * _heapwatch   Establishes read-only heap entries to be monitored
  436.  
  437.                     * _nheapwatch applies to the near heap (non-functional)
  438.                     * _fheapwatch applies to the far heap
  439.                     * _hheapwatch applies to the far heap
  440.  
  441.          hfree        Releases memory back to the far heap (reverse halloc)
  442.  
  443.          malloc       Allocates memory from the default heap
  444.  
  445.                       _nmalloc applies to the near heap
  446.                       _fmalloc applies to the far heap (size <= SIZE_MAX)
  447.                     * _hmalloc applies to the far heap (any size)
  448.  
  449.          _memavl      Estimates amount of memory available in near heap
  450.  
  451.          _memmax      Estimates size of largest free area in near heap
  452.  
  453.          _msize       Reports size of a default heap entry
  454.  
  455.                       _nmsize applies to the near heap
  456.                       _fmsize applies to the far heap (size <= SIZE_MAX)
  457.                     * _hmsize applies to the far heap (any size)
  458.  
  459.          realloc      Reallocates a block in the default heap
  460.  
  461.                     * _nrealloc applies to the near heap
  462.                     * _frealloc applies to the far heap (size <= SIZE_MAX)
  463.                     * _hrealloc applies to the far heap (any size)
  464.  
  465.        * _relocate    Repositions a block as low as possible in the detault heap 
  466.  
  467.                     * _nrelocate applies to the near heap
  468.                     * _frelocate applies to the far heap
  469.                     * _hrelocate applies to the far heap
  470.  
  471.          sbrk         Resets break value
  472.  
  473.          stackavail   Reports stack space available for alloca
  474.  
  475.  
  476.       b. Brief descriptions
  477.  
  478.          These functions are unique to the replacement heap manager
  479.          library.  The standard functions are described on page 69 of
  480.          the MSC 5.1 Optimizing Compiler Run-Time Library manual.
  481.  
  482.          _Heapdump() is a utility function that writes a complete
  483.          description of the state of the heap to the indicated
  484.          stream file.
  485.  
  486.          _Heappack() releases unused heap memory.  It searches the
  487.          entire heap, shrinking arenas that contain active entries
  488.          to the minimum, and totally freeing arenas that contain no
  489.          active entries.
  490.  
  491.          _Heapstat() translates heap status codes obtained from the
  492.          _heapchk/set/walk() functions into descriptive strings.
  493.  
  494.          _Heapwatch() establishes a heap entry as read-only.  It
  495.          records a checksum which is tested by the _heapchk/set/walk()
  496.          functions, and monitored by the _HEAPDEBUG and _HEAPTRACE
  497.          routines.
  498.  
  499.          _Relocate() repositions a heap entry as low as possible
  500.          in memory.  It is the basis for garbage collection to
  501.          relieve heap fragmentation, and, with _heappack(),
  502.          supports heap compaction.
  503.  
  504.  
  505.       5. Include files
  506.  
  507.          a. Heap.h
  508.  
  509.             The include file heap.h is a replacement for the MSC include
  510.             file malloc.h.  It provides transparent access to all of
  511.             the functionality of the original heap manager, plus the
  512.             extended capabilities of the replacement heap manager.  The
  513.             symbol STDMSC enforces strict compatibility by disabling all
  514.             the extended features of the replacement heap manager.
  515.  
  516.             Heap.h declares the following functions:
  517.                                           
  518.                 alloca            _heapchk          malloc     *
  519.                 calloc            _heapdump         _memavl
  520.                 _expand    *      _heappack         _memmax
  521.                 _fcalloc   *      _heapset          _msize     *
  522.                 _fexpand   *      _heapstat         _ncalloc
  523.                 _ffree     *      _heapwalk         _nexpand
  524.                 _fheapchk         _heapwatch        _nfree
  525.                 _fheapdump        _hexpand          _nheapchk
  526.                 _fheappack        hfree       @     _nheapdump
  527.                 _fheapset         _hfree            _nheappack
  528.                 _fheapwalk        _hheapchk         _nheapset
  529.                 _fheapwatch       _hheapdump        _nheapwalk
  530.                 _fmalloc   *      _hheappack        _nheapwatch
  531.                 _fmsize    *      _hheapset         _nmalloc
  532.                 _frealloc  *      _hheapwalk        _nmsize
  533.                 free       *      _hheapwatch       _nrealloc
  534.                 _freect           _hmalloc          _nrelocate
  535.                 _frelocate        _hmsize           realloc    *
  536.                 halloc     @      _hrealloc         _relocate
  537.                 _hcalloc          _hrelocate        sbrk
  538.                                                     stackavail
  539.  
  540.                 * these functions include bug fixes for zero-length
  541.                   entries and NULL pointers.
  542.  
  543.                 @ these functions are declared if STDMSC is defined.
  544.  
  545.  
  546.             SIZE_MAX is also declared in heap.h.
  547.  
  548.  
  549.          b. Heapdbg.h
  550.  
  551.             The include file heapdbg.h is an auxilliary include file
  552.             activated by the _HEAPDEBUG and _HEAPTRACE symbols.  It
  553.             declares alternates for the heap access functions.  It also
  554.             maps the original function names to the alternate function
  555.             names so that no source code changes are necessary to activate
  556.             the heap debugger.
  557.  
  558.  
  559.          c. Heap.i
  560.  
  561.             The include file heap.i is an internal header file for
  562.             the heap manager routines only.  It is not necessary
  563.             for any application program to include it.
  564.  
  565.             The heap.i file declares a variety of pre-processor macros
  566.             for use by the heap functions.  It also defines the internally
  567.             shared variables and functions.
  568.  
  569.  
  570. II. Reference
  571.  
  572.     The replacement heap managment functions are listed here, one per page,
  573.     in alphabetical order.  These descriptions rely on the information
  574.     contained in the MSC 5.1 Optimizing Compiler Run-Time Library Reference.
  575.  
  576.     The example programs were tested under all address models.
  577.  
  578.     It is instructive to examine the handling of the variants of the basic
  579.     functions.  The original library uses a number of methods for handling
  580.     variants based on address models.  Some functions have both far and near
  581.     variants with the mapping of the appropriate default model into the
  582.     generic function handled at run time.  E.g., malloc exists and uses the
  583.     default heap.  The explicit functions _fmalloc and _nmalloc allow programs
  584.     to access a particular heap independent of the default address model.
  585.     This is the most flexible arrangement.
  586.  
  587.     The heapchk/set/walk family of functions are implemented as macros that
  588.     map to the address-model-specific version, either _nheapchk/set/walk or
  589.     _fheapchk/set/walk.  This arrangement is a little strange as it provides
  590.     compile-time mapping, but must also support run-time mapping for modules
  591.     compiled without the inclusion of malloc.h.  Indeed, the xheapchk module
  592.     implements just such a run-time mapping.
  593.  
  594.     Another method of handling address width variation is to provide a single
  595.     default-heap-only function.  In fact, calloc, _expand, and realloc have
  596.     no explicit variants.  In a small model program you can _fmalloc and _ffree
  597.     but you cannot _fcalloc, _fexpand, or _frealloc.
  598.  
  599.     Perhaps the worst possible situation is that which controls _freect,
  600.     _memavl, and _memmax.  In spite of the documentation, these functions
  601.     only apply to the "near" heap.  There are no equivalents for the far heap.
  602.  
  603.     The replacement heap manager extends the capabilities of the heap manager
  604.     along two independent dimensions.  First, it adds new functions.  The
  605.     _heapdump, _heappack, _heapstat, _heapwatch, and _relocate functions are
  606.     unique to the replacement heap manager.  Second, the replacement heap
  607.     manager provides address-model-specific variants for all basic function
  608.     in all three address models an extension along the "near"-"far"-"huge"
  609.     axis, with the default always being either "near" or "far".  (Support
  610.     for a "huge" default model requires changes to other parts of the C
  611.     run-time library).
  612.  
  613.     The rules for function naming give three variations for address models.
  614.     All functions accept the prefixes '_n', '_f', and '_h'.  The "near"
  615.     functions use types size_t and near *.  The "far" functions use types
  616.     size_t and far *.  The "huge" functions use types long and huge *.
  617.  
  618.     The above rules do not apply to the non-heap related functions alloca,
  619.     sbrk, and stackavail.  Nor do they apply to the special purpose functions
  620.     _freect, halloc, hfree, _memavl, and _memmax.  All other functions follow
  621.     the rules. 
  622.  
  623.     Unfortunately this leaves us with both an hfree function and an _hfree
  624.     function.  This near collision is resolved by the symbol STDMSC.  If it
  625.     is defined then halloc and hfree are declared and _hfree, along with all
  626.     the other extended functions, is not declared.  If STDMSC is not defined
  627.     then halloc and hfree are not declared and will produce warnings about
  628.     lack of return values and prototypes.
  629.  
  630.  
  631. ALLOCA
  632.  
  633.     Summary
  634.  
  635.         #include <heap.h
  636.  
  637.         void *alloca( size );
  638.         size_t size;                    // Bytes to allocate
  639.  
  640.  
  641.     Differences
  642.  
  643.         None.
  644.  
  645.  
  646.     Further info
  647.  
  648.         See page 114 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  649.  
  650.  
  651. CALLOC
  652.  
  653.     Summary
  654.  
  655.         #include <heap.h>
  656.  
  657.         void *calloc( nitems, size )
  658.         size_t nitems;                  // Number of array elements
  659.         size_t size;                    // Bytes in each element
  660.  
  661.         void near *_ncalloc( nitems, size )
  662.         size_t nitems;                  // Number of array elements
  663.         size_t size;                    // Bytes in each element
  664.  
  665.         void far *_fcalloc( nitems, size )
  666.         size_t nitems;                  // Number of array elements
  667.         size_t size;                    // Bytes in each element
  668.  
  669.         void huge *_hcalloc( nitems, size )
  670.         long   nitems;                  // Number of array elements
  671.         size_t size;                    // Bytes in each element
  672.  
  673.  
  674.     Differences
  675.  
  676.         In "small" and "medium" model programs calloc and _ncalloc come
  677.         from the original library.  In "compact", "large", and "huge" model
  678.         programs _ncalloc comes from the replacement library and, because
  679.         there is no near heap, always returns NULL.
  680.  
  681.         The _fcalloc and _hcalloc functions always come from the replacement
  682.         library.  They differ from the original versions as follows:
  683.  
  684.             1. SIZE_MAX is 65535 rather than 65516.
  685.  
  686.             2. Zero-length entries are do not corrupt the heap.
  687.  
  688.         The _ncalloc, _fcalloc, and _hcalloc functions are unique to the
  689.         replacement heap manager.
  690.  
  691.  
  692.     Further info
  693.  
  694.         See page 150 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  695.  
  696.  
  697. _EXPAND
  698.  
  699.     Summary
  700.  
  701.         #include <heap.h>
  702.  
  703.         void *_expand( buffer, size )
  704.         void  *buffer;                  // Pointer to memory block
  705.         size_t size;                    // Desired number of bytes
  706.  
  707.         void near *_nexpand( buffer, size )
  708.         void near *buffer;              // Pointer to memory block
  709.         size_t size;                    // Desired number of bytes
  710.  
  711.         void far *_fexpand( buffer, size )
  712.         void far *buffer;               // Pointer to memory block
  713.         size_t size;                    // Desired number of bytes
  714.  
  715.         void huge *_hexpand( buffer, size )
  716.         void huge *buffer;              // Pointer to memory block
  717.         long size;                      // Desired number of bytes
  718.  
  719.  
  720.     Differences
  721.  
  722.         In "small" and "medium" model programs _expand and _nexpand
  723.         come from the original library.  In "compact", "large", and "huge"
  724.         model programs _nexpand comes from the replacement library and,
  725.         because there is no "near" heap, always returns NULL.
  726.  
  727.         The _fexpand and _hexpand functions always come from the
  728.         replacement library.  They differ from the original versions
  729.         as follows:
  730.  
  731.             1. SIZE_MAX is 65535 rather than 65516.
  732.  
  733.             2. Since the "huge" heap is part of the "far" heap,
  734.                _expand can handle any "huge" heap entry.
  735.  
  736.             3. Invalid pointers are detected and reported on stderr.
  737.  
  738.             4. Zero-length entries do not corrupt the heap.
  739.  
  740.         The _nexpand, _fexpand, and _hexpand functions are unique to the
  741.         replacement heap manager.
  742.  
  743.  
  744.     Further info
  745.  
  746.         See page 246 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  747.  
  748.  
  749. FREE
  750.  
  751.     Summary
  752.  
  753.         #include <heap.h>
  754.     
  755.         void free( buffer );
  756.         void *buffer;                   // Pointer to memory block
  757.  
  758.         void _nfree( buffer );
  759.         void near *buffer;              // Pointer to memory block
  760.  
  761.         void _ffree( buffer );
  762.         void far *buffer;               // Pointer to memory block
  763.  
  764.         void _hfree( buffer );
  765.         void huge *buffer;              // Pointer to memory block
  766.  
  767.  
  768.     Differences
  769.  
  770.         In "small" and "medium" model programs free and _nfree come from
  771.         the original library.  In "compact", "large", and "huge" model
  772.         programs _nfree comes from the replacement library and, because
  773.         there is no "near" heap, does nothing.
  774.  
  775.         The _ffree and _hfree functions always come from the replacement
  776.         library.  They differ from the original versions as follows:
  777.  
  778.             1. Since the "huge" heap is part of the "far" heap,
  779.                free can handle any "huge" heap entry.
  780.  
  781.             2. Invalid pointers are detected and reported on stderr.
  782.  
  783.  
  784.         Note that while hfree and _hfree have very similar names they
  785.         have radically different purposes.  The hfree function comes from
  786.         the original library and frees a region obtained from the
  787.         operating system by halloc.  The _hfree function comes from the
  788.         replacement library and is the "huge" version of free.
  789.  
  790.         This near collision is resolved by the STDMSC symbol.  When STDMSC
  791.         is defined halloc and hfree are declared and _hfree is not.  When
  792.         STDMSC is not defined halloc and hfree are not declared, but _hfree
  793.         and all the other extended functions are declared.
  794.  
  795.  
  796.     Further info
  797.  
  798.         See page 289 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  799.  
  800.  
  801. _FREECT
  802.  
  803.     Summary
  804.  
  805.         uint _freect( size );
  806.         size_t size;                    // Desired size of allocation
  807.  
  808.  
  809.     Differences
  810.  
  811.         In "small" and "medium" model programs _freect comes from the
  812.         original library.  In "compact", "large", and "huge" model
  813.         programs _freect comes from the replacement library and,
  814.         because there is no "near" heap, always returns zero.
  815.  
  816.  
  817.     Further info
  818.  
  819.         See page 291 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  820.  
  821.  
  822. HALLOC
  823.  
  824.     Summary
  825.  
  826.         #include <heap.h>
  827.  
  828.         #if defined ( STDMSC )
  829.  
  830.             void huge *halloc( nitems, size );
  831.             long   nitems;                  // Number of array elements
  832.             size_t size;                    // Bytes in each element
  833.  
  834.         #endif
  835.  
  836.  
  837.     Differences
  838.  
  839.         None.
  840.  
  841.         But note that halloc is not declared unless the symbol STDMSC
  842.         is defined.  The functions _hcalloc and _hmalloc superceed the
  843.         halloc function.
  844.  
  845.  
  846.     Further info
  847.  
  848.         See page 347 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  849.  
  850.  
  851. _HEAPCHK
  852.  
  853.     Summary
  854.  
  855.         #include <heap.h>
  856.  
  857.         int _heapchk( void );
  858.  
  859.         int _nheapchk( void );
  860.  
  861.         int _fheapchk( void );
  862.  
  863.         int _hheapchk( void );
  864.  
  865.  
  866.     Differences
  867.  
  868.         In "small" and "medium" model programs _heapchk and _nheapchk come
  869.         from the original library.  In "compact", "large", and "huge" model
  870.         programs _nheapchk comes from the replacement library and, because
  871.         there is no "near" heap, always returns _HEAPEMPTY.
  872.  
  873.         The _fheapchk and _hheapchk functions always come from the
  874.         replacement library.  They differ from the original versions
  875.         as follows:
  876.  
  877.             1. They perform a detailed consistency check on each heap
  878.                entry, verifying the validity of the heap control block
  879.                and checking its neighbors for reciprocity.
  880.  
  881.             2. The safety margins controlled by _heappad are inspected
  882.                for changes.  Any alteration of the safety margins
  883.                produces a _HEAPBADPTR result code.
  884.  
  885.             3. The checksums on the read-only heap entries established
  886.                by _heapwatch are recalculated.  A changed checksum
  887.                produces a _HEAPBADPTR result code
  888.  
  889.  
  890.     Further info
  891.  
  892.         See page 352 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  893.  
  894.  
  895. _HEAPDUMP
  896.  
  897.     Summary
  898.  
  899.         #include <heap.h>
  900.  
  901.         void _heapdump( stream, verbose );
  902.         FILE *stream;                       // Where to write the report
  903.         int verbose;                        // Whether to give details
  904.  
  905.         void _nheapdump( stream, verbose );
  906.         FILE *stream;
  907.         int verbose;
  908.  
  909.         void _fheapdump( stream, verbose );
  910.         FILE *stream;
  911.         int verbose;
  912.  
  913.         void _hheapdump( stream, verbose );
  914.         FILE *stream;
  915.         int verbose;
  916.  
  917.  
  918.     Description
  919.  
  920.         The _heapdump functions write a detailed report on the state of the
  921.         heap to a file.  The verbose flag controls the amount of detail in
  922.         the report.
  923.  
  924.         The reports on the "far" heap (_fheapdump and _hheapdump) include the
  925.         following information:
  926.  
  927.              - Key to notation
  928.  
  929.              - Global variables
  930.                 - _heapmode
  931.                 - _heappad
  932.  
  933.              - Arena headers -- DOS interface
  934.                 - Address [pointer]
  935.                 - Size
  936.                 - Links [pointers] on arena list
  937.                 - Source of the memory (DOS or non-DOS)
  938.                 - Chunk headers -- C interface
  939.                    - Address {<pointer>}
  940.                    - Size
  941.                    - Links <pointers> on chunk list
  942.                    - Links {pointers} on free list
  943.                    - Status: readonly, damaged, OK, etc.
  944.                    - In debug mode additional info is reported:
  945.                       - Function that last changed the entry
  946.                       - Desired size of the entry
  947.                       - Transaction (sequence) number
  948.                       - Name of source file (__FILE__)
  949.                       - Line number in source file (__LINE__)
  950.  
  951.              - Controls for free and join lists
  952.                 - Address {pointer}
  953.                 - Number of entries on the list (not including master)
  954.                 - Links {pointers}
  955.  
  956.              - Summary statistics on heap usage
  957.                 - Number of entries in the heap
  958.                 - Total heap memory
  959.                 - Percent of heap memory in use
  960.                 - Size of largest free block
  961.  
  962.              - Pagination: formfeed
  963.  
  964.  
  965.         The _nheapdump function describes the "near" heap.  It provides
  966.         the following information:
  967.  
  968.             - Description of each heap entry
  969.                - Address
  970.                - Size
  971.                - Status (used/free)
  972.  
  973.             - Summary statistics on heap usage
  974.                - Number of entries in the heap
  975.                - Total heap memory
  976.                - percent of heap memory in use
  977.                - Size of largest free block
  978.  
  979.             - Pagination: formfeed
  980.         
  981.  
  982.     Return Value
  983.  
  984.         None.
  985.  
  986.  
  987.     Differences
  988.  
  989.         The _heapdump function is unique to the replacement heap manager.
  990.  
  991.  
  992.     Example
  993.  
  994.         #include <stdio.h>
  995.  
  996.         #include <heap.h>
  997.  
  998.         int main()
  999.         {
  1000.         _fmalloc( 1000 );
  1001.  
  1002.         _fmalloc( 2000 );
  1003.  
  1004.         _fheapdump( stdout, 1 );
  1005.  
  1006.         return( 0 );
  1007.         }
  1008.  
  1009.         This program allocates two heap entries and then produces
  1010.         a report on the state of the heap.
  1011.  
  1012.  
  1013. _HEAPPACK
  1014.  
  1015.     Summary
  1016.  
  1017.         #include <heap.h>
  1018.  
  1019.         int _heappack( void );
  1020.  
  1021.         int _nheappack( void );
  1022.  
  1023.         int _fheappack( void );
  1024.  
  1025.         int _hheappack( void );
  1026.  
  1027.  
  1028.     Description
  1029.  
  1030.         The _heappack() function shrinks the heap to the minimum required
  1031.         to contain the in-use heap entries.  Currently only the "far" heap
  1032.         supports packing, but the _nheappack function exists as a stub
  1033.         which returns a successful result code.
  1034.  
  1035.  
  1036.     Return Value
  1037.  
  1038.         Zero if successful, otherwise a DOS error number.
  1039.  
  1040.  
  1041.     Differences
  1042.  
  1043.         The _heappack function is unique to the replacement heap manager.
  1044.  
  1045.  
  1046.     See Also
  1047.  
  1048.         _relocate
  1049.  
  1050.  
  1051.     Example
  1052.  
  1053.         #include <stdio.h>
  1054.  
  1055.         #include <heap.h>
  1056.  
  1057.         int main()
  1058.         {
  1059.         void far *p1 = _fmalloc( 1000 );
  1060.  
  1061.         void far *p2 = _fmalloc( 2000 );
  1062.  
  1063.         void far *p3 = _fmalloc( 3000 );
  1064.  
  1065.         _ffree( p2 );
  1066.  
  1067.         _ffree( p3 );
  1068.  
  1069.         printf("Before packing\n\n");
  1070.  
  1071.         _fheapdump( stdout, 1 );
  1072.  
  1073.         _fheappack();
  1074.  
  1075.         printf("After packing\n\n");
  1076.  
  1077.         _fheapdump( stdout, 1 );
  1078.  
  1079.         return( 0 );
  1080.         }
  1081.  
  1082.         This program allocates three heap entries and then frees the
  1083.         last two.  Then it packs the heap to minimize the amount of
  1084.         space taken up by the "far" heap.  The before and after heap
  1085.         reports illustrate the savings.
  1086.  
  1087.  
  1088. _HEAPSET
  1089.  
  1090.  
  1091.     Summary
  1092.  
  1093.         #include <heap.h>
  1094.  
  1095.         int _heapset( fill );
  1096.         uint fill;                  // Value to fill with
  1097.  
  1098.         int _nheapset( fill );
  1099.         uint fill;                  // Value to fill with
  1100.  
  1101.         int _fheapset( fill );
  1102.         uint fill;                  // Value to fill with
  1103.  
  1104.         int _hheapset( fill );
  1105.         uint fill;                  // Value to fill with
  1106.  
  1107.  
  1108.     Differences
  1109.  
  1110.         In "small" and "medium" model programs _heapset and _nheapset come
  1111.         from the original library.  In "compact", "large", and "huge" model
  1112.         programs _nheapset comes from the replacement library and, because
  1113.         there is no "near" heap, always returns _HEAPEMPTY.
  1114.  
  1115.         The _fheapset and _hheapset functions always come from the
  1116.         replacement library.  They differ from the original versions
  1117.         as follows:
  1118.  
  1119.             1. They perform a detailed consistency check on each heap
  1120.                entry, verifying the validity of the heap control block
  1121.                and checking its neighbors for reciprocity.
  1122.  
  1123.             2. The safety margins controlled by _heappad are inspected
  1124.                for changes.  Any alteration of the safety margins
  1125.                produces a _HEAPBADPTR result code.
  1126.  
  1127.             3. The checksums on the read-only heap entries established
  1128.                by _heapwatch are recalculated.  A changed checksum
  1129.                produces a _HEAPBADPTR result code
  1130.  
  1131.             4. The default safety margin fill value is reset by each call
  1132.                to _heapset.
  1133.  
  1134.  
  1135.     Further info
  1136.  
  1137.         See page 354 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  1138.  
  1139.  
  1140. _HEAPSTAT
  1141.  
  1142.     Summary
  1143.  
  1144.         #include <heap.h>
  1145.  
  1146.         char *_heapstat( status )
  1147.         int status;                     // Status code from _heapchk/set/walk
  1148.  
  1149.  
  1150.     Description
  1151.  
  1152.         The _heapstat function translates heap status codes into descriptive
  1153.         strings.  Invalid status codes are also reported as such.
  1154.  
  1155.         The translation is as follows:
  1156.  
  1157.             _HEAPEMPTY      Heap not initialized
  1158.  
  1159.             _HEAPOK         Heap is OK
  1160.  
  1161.             _HEAPBADBEGIN   Master heap data corrupt
  1162.  
  1163.             _HEAPBADNODE    Bad heap control block
  1164.  
  1165.             _HEAPEND        End of heap
  1166.  
  1167.             _HEAPBADPTR     Bad pointer or data corrupted
  1168.  
  1169.             all others      Unknown heap status code
  1170.  
  1171.  
  1172.     Differences
  1173.  
  1174.         The _heapstat function is unique to the replacement heap manager.
  1175.  
  1176.  
  1177.     Return Value
  1178.  
  1179.         The _heapstat function returns a pointer to the string containing
  1180.         the status message.
  1181.  
  1182.  
  1183.     Example
  1184.  
  1185.         #include <stdio.h>
  1186.  
  1187.         #include <heap.h>
  1188.  
  1189.         int main()
  1190.         {
  1191.         printf("Heap status : %s\n", _heapstat( _heapchk() ) );
  1192.  
  1193.         malloc( 1234 );
  1194.  
  1195.         printf("Heap status : %s\n", _heapstat( _heapchk() ) );
  1196.  
  1197.         return( 0 );
  1198.         }
  1199.  
  1200.         This program checks the heap status before and after the heap is
  1201.         initialized.  If the heap is not consistent it prints out
  1202.         a error message.
  1203.  
  1204.  
  1205. _HEAPWALK
  1206.  
  1207.     Summary
  1208.  
  1209.         #include <heap.h>
  1210.  
  1211.         int _heapwalk( info );      // Implemented as a macro
  1212.         struct _heapinfo *info;     // Info on one heap entry
  1213.  
  1214.  
  1215.     Differences
  1216.  
  1217.         In "small" and "medium" model programs _heapwalk and _nheapwalk come
  1218.         from the original library.  In "compact", "large", and "huge" model
  1219.         programs _nheapset comes from the replacement library and, because
  1220.         there is no "near" heap, always returns _HEAPEMPTY.
  1221.  
  1222.         The _fheapwalk and _hheapwalk functions always come from the
  1223.         replacement library.  They differ from the original versions
  1224.         as follows:
  1225.  
  1226.             1. They perform a detailed consistency check on each heap
  1227.                entry, verifying the validity of the heap control block
  1228.                and checking its neighbors for reciprocity.
  1229.  
  1230.             2. The safety margins controlled by _heappad are inspected
  1231.                for changes.  Any alteration of the safety margins
  1232.                produces a _HEAPBADPTR result code.
  1233.  
  1234.             3. The checksums on the read-only heap entries established
  1235.                by _heapwatch are recalculated.  A changed checksum
  1236.                produces a _HEAPBADPTR result code
  1237.  
  1238.  
  1239.     Further info
  1240.  
  1241.         See page 356 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  1242.  
  1243.  
  1244. _HEAPWATCH
  1245.  
  1246.     Summary
  1247.  
  1248.         #include <heap.h>
  1249.  
  1250.         int _heapwatch( buffer, enable )
  1251.         void *buffer;               // Pointer to memory block
  1252.         int   enable;               // Turns monitoring on and off
  1253.  
  1254.         int _nheapwatch( buffer, enable )
  1255.         void near *buffer;          // Pointer to memory block
  1256.         int        enable;          // Turns monitoring on and off
  1257.  
  1258.         int _fheapwatch( buffer, enable )
  1259.         void far *buffer;           // Pointer to memory block
  1260.         int       enable;           // Turns monitoring on and off
  1261.  
  1262.         int _hheapwatch( buffer, enable )
  1263.         void huge *buffer;          // Pointer to memory block
  1264.         int        enable;          // Turns monitoring on and off
  1265.  
  1266.  
  1267.     Description
  1268.  
  1269.         The _heapwatch function establishes a heap entry as read-only.
  1270.         The region is checksummed, and the _heapchk/set/walk family of
  1271.         functions verify the integrity of the entry by recalculating
  1272.         the checksum.  The heap debug monitor also checks the read-only
  1273.         entries and triggers a diagnostic report if one is changed.
  1274.  
  1275.         If the enable argument is TRUE the checksum is calculated and
  1276.         the region is treated as read-only.  If the enable argument is
  1277.         FALSE the region loses its read-only status.
  1278.  
  1279.         A program may alter a read-only heap entry and inform the heap
  1280.         manager that the change is not an error by calling _heapwatch
  1281.         after each alteration.
  1282.  
  1283.         Invalid pointers to "far" heap entries are detected and reported
  1284.         on stderr.
  1285.  
  1286.         Note that _expand, free, realloc, and _relocate automatically
  1287.         remove the read-only status of a heap entry.
  1288.  
  1289.         The _nheapwatch function is not currently implemented.  It is
  1290.         a stub that always returns a failure code.
  1291.  
  1292.  
  1293.     Return Value
  1294.  
  1295.         A successful invocation returns zero.  If the pointer does not
  1296.         address a valid heap entry _heapwatch returns non-zero.
  1297.  
  1298.  
  1299.     Differences
  1300.  
  1301.         The _heapwatch function is unique to the replacement heap manager.
  1302.  
  1303.  
  1304.     Example
  1305.  
  1306.         #include <stdio.h>
  1307.  
  1308.         #include <heap.h>
  1309.  
  1310.         void report( char *position );
  1311.  
  1312.         int main()
  1313.         {
  1314.         int index;
  1315.  
  1316.         char far *ptr = _fmalloc( 100 );
  1317.  
  1318.         for ( index=0 ; index<100 ; index++ )
  1319.  
  1320.             ptr[index] = (char) index;
  1321.  
  1322.         _fheapwatch( ptr, 1 );              // establishes the enty as read-only
  1323.  
  1324.         report( "read-only enabled" );      // should not detect an error
  1325.  
  1326.         ptr[0] = -1;                        // change part of the data
  1327.  
  1328.         report( "data modified" );          // should detect an error
  1329.  
  1330.         _fheapwatch( ptr, 0 );              // stop watching this region
  1331.  
  1332.         report( "read-only disabled" );     // should not detect an error
  1333.  
  1334.         return( 0 );
  1335.         }
  1336.  
  1337.         void report( char *position )
  1338.         {
  1339.         int status = _fheapchk();
  1340.  
  1341.         printf( "Heap status after %s : %s\n", position, _heapstat(status) );
  1342.         }
  1343.  
  1344.         This program allocates a region of 100 bytes and fills it with data.
  1345.         It then declares the region to be read-only, and checks that _fheapchk
  1346.         reports the heap as intact.  Then the program changes the data, and
  1347.         checks the heap status again.  At this point the error should be
  1348.         detected.  Finally, the program unprotects the region and verifies
  1349.         that _fheapchk stops complaining.
  1350.  
  1351.  
  1352. HFREE
  1353.  
  1354.     Summary
  1355.  
  1356.         #include <heap.h>
  1357.  
  1358.         #if defined ( STDMSC )
  1359.  
  1360.             void hfree( buffer );
  1361.             void huge *buffer;          // Pointer to memory block
  1362.  
  1363.         #endif
  1364.  
  1365.  
  1366.     Differences
  1367.  
  1368.         None.
  1369.  
  1370.         But note that while hfree and _hfree have very similar names they
  1371.         have radically different purposes.  The hfree function comes from
  1372.         the original library and frees a region obtained from the
  1373.         operating system by halloc.  The _hfree function comes from the
  1374.         replacement library and is the "huge" version of free.
  1375.  
  1376.         This near collision is resolved by the STDMSC symbol.  When STDMSC
  1377.         is defined halloc and hfree are declared and _hfree is not.  When
  1378.         STDMSC is not defined halloc and hfree are not declared, but hfree
  1379.         and all the other extended functions are declared.
  1380.  
  1381.  
  1382.     Further info
  1383.  
  1384.         See page 359 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  1385.  
  1386. MALLOC
  1387.  
  1388.     Summary
  1389.  
  1390.         #include <heap.h>
  1391.  
  1392.         void *malloc( size );       // Allocate memory from default heap
  1393.         size_t size;                // Bytes to allocate
  1394.  
  1395.         void near *_nmalloc( size );// Allocate memory from "near" heap
  1396.         size_t size;                // Bytes to allocate
  1397.  
  1398.         void far *_fmalloc( size ); // Allocate memory from "far" heap
  1399.         size_t size;                // Bytes to allocate
  1400.  
  1401.         void huge *_hmalloc( size );// Allocate memory from "far" heap
  1402.         long size;                  // Bytes to allocate
  1403.  
  1404.  
  1405.     Differences
  1406.  
  1407.         In "small" and "medium" model programs malloc and _nmalloc come
  1408.         from the original library.  In "compact", "large", and "huge" model
  1409.         programs _nmalloc comes from the replacement library and, because
  1410.         there is no near heap, always returns NULL.
  1411.  
  1412.         The _fmalloc and _hmalloc functions always come from the replacement
  1413.         library.  They differ from the original versions as follows:
  1414.  
  1415.             1. SIZE_MAX is 65535 rather than 65516.
  1416.  
  1417.             2. Zero-length entries do not corrupt the heap.
  1418.  
  1419.  
  1420.     Further info
  1421.  
  1422.         See page 409 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  1423.  
  1424.  
  1425. _MEMAVL
  1426.  
  1427.     Summary
  1428.  
  1429.         #include <heap.h>
  1430.  
  1431.         size_t _memavl( void );
  1432.  
  1433.     Differences
  1434.  
  1435.         In "small" and "medium" model programs _memavl comes from the
  1436.         original library.  In "compact", "large", and "huge" model
  1437.         programs _memavl comes from the replacement library and,
  1438.         because there is no "near" heap, always returns zero.
  1439.  
  1440.  
  1441.     Further info
  1442.  
  1443.         See page 414 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  1444.  
  1445.  
  1446. _MEMMAX
  1447.  
  1448.     Summary
  1449.  
  1450.         #include
  1451.  
  1452.         size_t _memmax( void );
  1453.  
  1454.     Differences
  1455.  
  1456.         In "small" and "medium" model programs _memmax comes from the
  1457.         original library.  In "compact", "large", and "huge" model
  1458.         programs _memmax comes from the replacement library and,
  1459.         because there is no "near" heap, always returns zero.
  1460.  
  1461.  
  1462.     Further info
  1463.  
  1464.         See page 425 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  1465.  
  1466.  
  1467. _MSIZE
  1468.  
  1469.     Summary
  1470.  
  1471.         #include <heap.h>
  1472.  
  1473.         size_t _msize( buffer );
  1474.         void *buffer;               // Pointer to memory block
  1475.  
  1476.         size_t _nmsize( buffer );
  1477.         void near *buffer;          // Pointer to memory block
  1478.  
  1479.         size_t _fmsize( buffer );
  1480.         void far *buffer;           // Pointer to memory block
  1481.  
  1482.         long _hmsize( buffer );
  1483.         void huge *buffer;          // Pointer to memory block
  1484.  
  1485.  
  1486.     Differences
  1487.  
  1488.         In "small" and "medium" model programs _msize and _nmsize come
  1489.         from the original library.  In "compact", "large", and "huge"
  1490.         model programs _nmsize comes from the replacement library and,
  1491.         because there is no "near" heap, always returns zero.
  1492.  
  1493.         The _fmsize and _hmsize functions always come from the
  1494.         replacement library.  They differ from the original versions
  1495.         as follows:
  1496.  
  1497.             1. Since the "huge" heap is part of the "far" heap,
  1498.                _fmsize can handle any "huge" heap entry.  However,
  1499.                it cannot return the actual size because size_t is
  1500.                too narrow, so it returns SIZE_MAX (65535).  The
  1501.                solution is to use _hmsize for all "far" and "huge"
  1502.                heap entries.
  1503.  
  1504.             2. NULL pointers have size zero rather than garbage.
  1505.  
  1506.             3. Invalid pointers are detected and reported on stderr.
  1507.  
  1508.  
  1509.     Further info
  1510.  
  1511.         See page 440 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  1512.  
  1513.  
  1514. REALLOC
  1515.  
  1516.     Summary
  1517.  
  1518.         #include <heap.h>
  1519.  
  1520.         void *realloc( buffer, size );
  1521.         void  *buffer;                  // Pointer to memory block
  1522.         size_t size;                    // Desired number of bytes
  1523.  
  1524.         void near *_nrealloc( buffer, size );
  1525.         void near *buffer;              // Pointer to memory block
  1526.         size_t     size;                // Desired number of bytes
  1527.  
  1528.         void far *_frealloc( buffer, size );
  1529.         void far *buffer;               // Pointer to memory block
  1530.         size_t    size;                 // Desired number of bytes
  1531.  
  1532.         void huge *_hrealloc( buffer, size );
  1533.         void huge *buffer;              // Pointer to memory block
  1534.         long       size;                // Desired number of bytes
  1535.  
  1536.  
  1537.     Differences
  1538.  
  1539.         In "small" and "medium" model programs realloc and _nrealloc
  1540.         come from the original library.  In "compact", "large", and "huge"
  1541.         model programs _nrealloc comes from the replacement library and,
  1542.         because there is no "near" heap, always returns NULL.
  1543.  
  1544.         The _frealloc and _hrealloc functions always come from the
  1545.         replacement library.  They differ from the original versions
  1546.         as follows:
  1547.  
  1548.             1. SIZE_MAX is 65535 rather than 65516.
  1549.  
  1550.             2. Since the "huge" heap is part of the "far" heap,
  1551.                realloc can handle any "huge" heap entry.
  1552.  
  1553.             3. Invalid pointers are detected and reported on stderr.
  1554.  
  1555.             4. Zero-length entries do not corrupt the heap.
  1556.  
  1557.             5. The original realloc returned NULL when given a pointer
  1558.                and a zero size as arguments.  The replacement realloc
  1559.                returns a zero-length heap entry, in keeping with the
  1560.                other forms of realloc and the other allocation functions.
  1561.  
  1562.         The _nrealloc, _frealloc, and _hrealloc functions are unique to the
  1563.         replacement heap manager.
  1564.  
  1565.  
  1566.     Further info
  1567.  
  1568.         See page 483 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  1569.  
  1570.  
  1571. _RELOCATE
  1572.  
  1573.     Summary
  1574.  
  1575.         #include <heap.h
  1576.  
  1577.         void *_relocate( buffer );
  1578.         void *buffer;                   // Pointer to memory block
  1579.  
  1580.         void near *_nrelocate( buffer );
  1581.         void near *buffer;              // Pointer to memory block
  1582.  
  1583.         void far *_frelocate( buffer );
  1584.         void far *buffer;               // Pointer to memory block
  1585.  
  1586.         void huge *_hrelocate( buffer );
  1587.         void huge *buffer;              // Pointer to memory block
  1588.  
  1589.  
  1590.     Description
  1591.  
  1592.         The _relocate function moves a heap entry as low as possible
  1593.         in memory.  It scans the free list looking for the block that
  1594.         has the lowest address and is large enough to contain the data.
  1595.         If it finds one it copies the old entry to the new region and
  1596.         frees the old entry.
  1597.  
  1598.         The "far" heap also supports sliding entries downward into
  1599.         adjacent free blocks.  If the search for a free block fails
  1600.         the preceeding block is checked.  If it is free it swaps places
  1601.         with the data block.  The combination of the two techiques
  1602.         guarantees that a single pass from low address to high address
  1603.         through the in-use heap entries will always compact the heap fully.
  1604.         I.e., all free space will be collected into a single entry at the
  1605.         top of the heap.
  1606.  
  1607.         Since the "huge" heap is part of the "far" heap, _frelocate can
  1608.         handle any "huge" heap entry.
  1609.  
  1610.         Invalid pointers to "far" heap entries are detected and
  1611.         reported on stderr,
  1612.  
  1613.  
  1614.     Return Value
  1615.  
  1616.         If the entry is moved _relocate returns a pointer to the new
  1617.         entry.  If the entry cannot be moved _relocate returns NULL.
  1618.  
  1619.  
  1620.     Differences
  1621.  
  1622.         The _relocate function is unique to the replacement heap manager.
  1623.  
  1624.  
  1625.     Example
  1626.  
  1627.         #include <stdio.h>
  1628.  
  1629.         #include <heap.h>
  1630.  
  1631.         int main()
  1632.         {
  1633.         void far *p1 = _fmalloc( 1000 );
  1634.  
  1635.         void far *p2 = _fmalloc( 2000 );
  1636.  
  1637.         void far *p3 = _fmalloc( 3000 );
  1638.  
  1639.         void far *p4 = _fmalloc( 4000 );
  1640.  
  1641.         void far *new;
  1642.  
  1643.         _ffree( p1 );
  1644.  
  1645.         _ffree( p3 );
  1646.  
  1647.         printf("Before relocation\n\n");
  1648.  
  1649.         _fheapdump( stdout, 1 );
  1650.  
  1651.         new = _frelocate( p2 );   if (new != NULL)   p2 = new;
  1652.  
  1653.         new = _frelocate( p4 );   if (new != NULL)   p4 = new;
  1654.  
  1655.         printf("After relocation\n\n");
  1656.  
  1657.         _fheapdump( stdout, 1 );
  1658.  
  1659.         return( 0 );
  1660.         }
  1661.  
  1662.         This program allocates four heap entries and then frees the
  1663.         first and third, leaving the second in the middle of the heap
  1664.         and the fourth at the end of the heap.  Then it relocates the
  1665.         two remaining entries to maximize the size of the free area.
  1666.         The before and after heap reports illustrate the compaction.
  1667.  
  1668.  
  1669. SBRK
  1670.  
  1671.     Summary
  1672.  
  1673.         #include <heap.h>
  1674.  
  1675.         void *sbrk( delta );
  1676.         int delta;                      // Bytes to add to the "break value"
  1677.  
  1678.  
  1679.     Differences
  1680.  
  1681.         None.
  1682.  
  1683.  
  1684.     Further info
  1685.  
  1686.         See page 499 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  1687.  
  1688.  
  1689. STACKAVAIL
  1690.  
  1691.     Summary
  1692.  
  1693.         #include <heap.h>
  1694.  
  1695.         size_t stackavail( void );
  1696.  
  1697.  
  1698.     Difference
  1699.  
  1700.         None.
  1701.  
  1702.  
  1703.     Further info
  1704.  
  1705.         See page 568 of the MSC 5.1 Optimizing Compiler Run-Time Reference
  1706.  
  1707.